Fritz: All Fritz

home *** CD-ROM | disk | FTP | other *** search

/ Fritz: All Fritz / All Fritz.zip / All Fritz / FILES / PROGASIC / STRBASIC.LZH / SB.DOC < prev next >

Wrap

Text File | 1984-10-10 | 30KB | 1,021 lines

October 1984 This document tells how to use the Structured BASIC preprocessor program, SB.EXE, and tells how to write programs for the IBM PC in the Structured BASIC language. This manual assumes you are familiar with MS DOS and Microsoft BASIC. THE BASIC NECESSITIES THE BASIC NECESSITIES PREPROCESSOR USER'S MANUAL PREPROCESSOR USER'S MANUAL Manual version: 1.12 Software version: 1.12 Marty Franz 525 W. Walnut St., Kalamazoo, MI 49007 (616) 344-1821 (C) Copyright 1983 Marty Franz - All rights reserved 100784112 Preprocessor User's Manual INTRODUCTION INTRODUCTION SB.EXE is a preprocessor program for Microsoft BASIC on the IBM PC. It takes a program containing special Structured BASIC statements and translates it into a program containing BASIC statements. Using SB.EXE helps you write more concise, better structured BASIC programs, because the preprocessor lets you take advantage of these features: - you now have the ability to write free-form, indented statements without line numbers. - you can now include statements from many separate files into a single BASIC program. This lets you write and maintain your programs in small modules. - you can organize your subroutines into procedures, each with its own alphanumeric name. - you can use structured programming statements similar to those found in programming languages like Pascal and C. Before using SB.EXE, please take the time to read these instructions carefully. When using it, bear in mind that this is version 1.12 of the program, and there may be bugs in it. If there is, or you have suggestions on improving Structured BASIC, please contact me: Marty Franz 525 W. Walnut St. Kalamazoo, MI 49007 (616) 344-2043 One more thing: the program, and this manual, are copyrighted materials. They may be freely distributed only for private, noncommercial use. Please read the copyright notice on your diskette. A SAMPLE PROGRAM A SAMPLE PROGRAM Before describing Structured BASIC in too much detail, let's first look at a typical program. This will help you understand what SB.EXE does. The file LC.SB on the diskette is a good example. It asks for the name of a text file and counts the number of lines in it. You can make a listing of LC.SB on your printer with the PRINT program supplied on the diskette: A>llist lc (See the Utilities Manual for more information on the LLIST _________ ______ program.) Page 2 100784112 Preprocessor User's Manual Your listing of LC.SB should look like this: 'Sample program to count the lines in an ASCII file. procedure MAIN on error goto CHECK.FOR.EOF input "File Name"; FILE.NAME$ open FILE.NAME$ for input as #1 LINE.COUNT = 0 : DONE.SW = 0 repeat line input #1, L$ LINE.COUNT = LINE.COUNT+1 until DONE.SW = 1 print "There are";LINE.COUNT-1;"lines in ";FILE.NAME$ endproc CHECK.FOR.EOF| ERROR.CODE = err : ERROR.LINE = erl if ERROR.CODE = 62 DONE.SW = 1 resume next else print "BASIC error ";ERROR.CODE;"at";ERROR.LINE stop 'Immediately halt program endif end This file (called a source file in this manual) was created ______ ____ using the ED.EXE program. For more information about ED, see the separate file about it on the diskette. Don't worry at this point about the details of each statement in the program; we'll be covering them shortly. For now, notice only that a Structured BASIC program, unlike a normal BASIC program, has line-number- free, neatly indented statements, and empty lines to separate blocks of statements. In fact, it resembles those Pascal programs you've seen in magazines more than BASIC. Because the program looks more structured than BASIC, it ought to be easier to understand and maintain. Unfortunately, this program cannot be executed directly by BASIC. We need to convert this program into one with everyday BASIC statements in it before we can run it. This is what SB.EXE does. To build a BASIC program out of LC.SB, we enter: A>sb lc and these messages appear: Page 3 100784112 Preprocessor User's Manual The Structured BASIC preprocessor 1.12 60KB to spare Done with pass 2, 0 error(s) found. 22 lines processed, 147 lines/minute. A> After the SB.EXE is done, if we then type the output file, LC.BAS, we see: A>type lc.bas 10 'LC.SB 10-14-83 5:48a 22 lines 20 GOSUB 50 30 END 40 'Sample program to count the lines in an ASCII file 50 'procedure MAIN 60 on error goto 150 70 input "File Name"; FILE.NAME$ 80 open FILE.NAME$ for input as #1 90 LINE.COUNT = 0 : DONE.SW = 0 100 line input #1, L$ 110 LINE.COUNT = LINE.COUNT+1 120 IF NOT(DONE.SW = 1) THEN 100 130 print "There are";LINE.COUNT-1;"lines in ";FILE.NAME$ 140 RETURN 150 'CHECK.FOR.EOF| 160 ERROR.CODE = ERR : ERROR.LINE = ERL 170 IF NOT(ERROR.CODE = 62) THEN 210 180 DONE.SW = 1 190 resume next 200 GOTO 230 210 print "BASIC error ";ERROR.CODE;"at";ERROR.LINE 220 stop 'Immediately halt program 230 end A> This is a conventional BASIC program that can now be run using ____ BASIC or BASICA. Page 4 100784112 Preprocessor User's Manual To summarize our example, which demonstrated the process of creating a Structured BASIC program: 1. We first use a text editor to write the program. The program contains special Structured BASIC statements (which we'll cover soon), is free of line numbers, has lots of blank lines and indenting, and is easier to read and maintain than regular BASIC. 2. We then use the preprocessor program, SB.EXE, to translate the program into one with everyday BASIC statements in it. 3. The translated BASIC program is now run and debugged as usual from BASIC. PROGRAM REQUIREMENTS PROGRAM REQUIREMENTS To preprocess Structured BASIC programs, you need an IBM PC, jr, or XT with: - at least 64KB of memory, - at least one single-sided diskette drive, - a color or monochrome adapter, with a monitor capable of displaying 80-character lines. - MS DOS version 1.1 or 2.x, and - BASIC.COM or BASICA.COM You also need the file SB.EXE available on the diskette with BASIC or BASICA. Page 5 100784112 Preprocessor User's Manual STRUCTURED BASIC STATEMENTS STRUCTURED BASIC STATEMENTS Your source program is composed of Structured BASIC statements. A Structured BASIC statement is similar to an everyday BASIC statement, except the line number is missing: SB supplies this for you when it builds the BASIC program from your source program. If 10 PRINT "Hello, world" is a BASIC statement, then PRINT "Hello, world" is the matching Structured BASIC statement. Only the line number is missing. You can have any number of blanks and tab characters in your source statements. In fact, this is encouraged since this helps make your Structured BASIC programs easier to read. Page 6 100784112 Preprocessor User's Manual LABELS LABELS Without line numbers in front of statements, you need another way to mark the places in a program where control is to go during its execution. You can do this in Structured BASIC with alphanumeric labels instead of line numbers. In a BASIC program, we might write two statements as: 960 GOTO 1030 and 1030 STOP 'End the program In Structured BASIC, these two statements would be written instead as: GOTO THE.END and THE.END| STOP Labels can be from 1 to 32 characters in length. Only the characters 0-9, A-Z, a-z, and "." (period) can be in a label. This is to keep labels from conflicting from other BASIC keywords. The "|" (vertical bar) is used only where the label is defined; notice that it's not there in the GOTO statement. It's used to set the label off from the rest of the line. Another example of labels in a Structured BASIC program is in LC.SB. The statements: on error goto CHECK.FOR.EOF and CHECK.FOR.EOF| also demonstrate how labels are referenced (the ON GOTO statement) and defined (the CHECK.FOR.EOF| statement) in Structured BASIC. The Structured BASIC statements that can use labels are: ON ERROR GOTO {label} ON n GOTO {label1},{label2},... RESTORE {label} RESUME {label} RETURN {label} Page 7 100784112 Preprocessor User's Manual PROCEDURES PROCEDURES Structured BASIC provides procedures to help organize your programs. Procedures are similar to BASIC subroutines, except they are identified by and called with an alphanumeric name. Procedures in Structured BASIC look like this: PROCEDURE {procname} _________ statements making up the procedure ENDPROC _______ To GOSUB to a procedure you can use either: GOSUB {procname} _____ or DO {procname} __ with the rules for procedure names being the same as for label names. The other Structured BASIC statements that can call procedures are: ON n DO {procname1},{procname2},... ON COM(n) DO {procname} ON KEY(n) DO {procname} ON PEN DO {name} ON PLAY(n) DO {procname} ON STRIG(n) DO {procname} ON TIMER(n) DO {procname} Every Structured BASIC program requires at least one procedure, called MAIN. Control is always given to MAIN with a GOSUB when the program is started (see lines 10-50 of LC.BAS). So, our "Hello, world" example needs three statements to work properly: PROCEDURE MAIN PRINT "Hello, world" ENDPROC Like white space, you should liberally use procedures in your Structured BASIC programs. They help break your program into chunks for better organization. Even a single statement deserves its own procedure if doing so will make the program easier to read. Page 8 100784112 Preprocessor User's Manual IF BLOCKS IF BLOCKS The only place in your Structured BASIC programs where you can't freely use a label to stand for a line number is in an IF statement. Instead, a special form of IF is used in Structured BASIC, called an "IF block". It looks like this: IF {condition1} __ statements executed if {condition1} is true ELSEIF {condition2} ______ statements executed if {condition2} is true ELSE ____ statements executed if both conditions are false ENDIF _____ An example of an IF block is in LC.SB: if ERROR.CODE = 62 DONE.SW = 1 resume next else print "BASIC error ";ERROR.CODE;"at";ERROR.LINE stop 'Immediately halt program endif Briefly, IF the variable ERROR.CODE has the value 62 then the statements DONE.SW = 1 and RESUME NEXT will be executed. This will occur if we have reached the end of the file we are reading. If ERROR.CODE is not 62, then another, more sinister BASIC error has occurred that we don't know how to handle. The statements after the ELSE display the error code and line number and stop the program. There can be more than one ELSEIF clause in the IF block. This is used to check for multiplie conditions without nesting single IF-ELSE-ENDIF blocks deeper and deeper. Why should you use IF blocks in a Structured BASIC program instead of BASIC's IF {condition} THEN {line number} statement? Because the IF block gives you the advantage of always knowing exactly where control begins and ends: with no GOTO statements in the IF and ELSE parts of the block, execution beginning at the IF statement will always resume after the ENDIF statement, regardless of what happens in between. With BASIC's IF statement, you can picture control splitting into two separate paths with each THEN. Pretty soon, as patches and revisions are made, your program becomes a mess of "spaghetti code". Page 9 100784112 Preprocessor User's Manual If you faithfully use the IF block for your program's logic you should seldom find the need for a GOTO statement. GOTOs should be saved only for unusual conditions that require special processing, such as errors. If you should require a GOTO, or you want to execute just a single statement with an IF, Structured BASIC provides a special "short form" of the IF for your convenience. In addition to the block format described above, you can use one of these formats: IF {condition} BREAK IF {condition} DO {procname} IF {condition} GOSUB {procname} IF {condition} GOTO {label} IF {condition} THEN {any BASIC statement} These statements are for the IF only and cannot be paired with an ELSEIF, ELSE, or ENDIF. They are intended for single-statement use only. Page 10 100784112 Preprocessor User's Manual REPEAT AND WHILE BLOCKS REPEAT AND WHILE BLOCKS Right now, many of your program loops in BASIC are written using IFs and GOTOs. To help make these more structured, Structured BASIC provides a REPEAT block for executing a group of statements over and over until a terminating condition is reached. It looks like this: REPEAT ______ statements to keep repeating UNTIL {condition} _____ A REPEAT block is used in LC.SB: repeat LINE INPUT #1, L$ LINE.COUNT = LINE.COUNT+1 until DONE.SW = 1 Remember that REPEAT is like any loop you might make with GOTOs in BASIC: you need to change something at some point in the statements you're repeating to stop the loop or you'll continue forever. Besides meeting the condition for termination, you can use a BREAK statement in the REPEAT block to transfer control immediately outside the loop. To use a BREAK statement, simply specify BREAK _____ Besides REPEAT, Structured BASIC provides a WHILE loop similar to the one already in Microsoft BASIC: WHILE {condition} _____ statements to repeat while {condition} is true ENDWHILE ________ When using the WHILE block, remember that the {condition} is tested before the statements in the body of the loop are ever executed, so it's possible to not do them at all. Also, be sure you use ENDWHILE instead of WEND in Structured BASIC, or SB.EXE will give you an error message. When the BASIC program is generated, a WHILE block will not have any Microsoft WHILE statements in it. Instead, IFs and GOTOs are used to make the loop, so the program can be converted to computers that don't have as advanced a version of BASIC. You can also use BREAK to get out of a WHILE loop. Page 11 100784112 Preprocessor User's Manual INCLUDE FILES INCLUDE FILES A useful technique in programming is designing a program as a set of small, independent modules. This makes programs easier to change, since revisions (like a changing the layout of a file) only affect a small component (the subroutines that read or write the file). Modular programming is hard to do with BASIC because all the pieces of your program must be present in a single file, with one set of line numbers. To help you develop your programs as small modules, Structured BASIC has an INCLUDE statement. Before telling you what it does, here's what it looks like: INCLUDE {filename.ext} _____ INCLUDE is used to bring statements into a program from a completely separate file during preprocessing, to be part of the program when it's translated into BASIC. The statements in the "included" file are also Structured BASIC statements. They can define and reference labels, procedures, and blocks exactly as if they were in the original source file. In fact, the INCLUDEd file can itself have INCLUDE statements in it. INCLUDE is an extremely useful feature of Structured BASIC, because now you can write frequently-used pieces of programs, such as input routines and screen formatters, once as sets of Structured BASIC procedures and just INCLUDE them into each new program that you write. When you edit these new programs you don't have to manually APPEND the pieces, since SB.EXE will automatically take care of the line numbering for you. (But not the variables.) MULTIPLE STATEMENTS MULTIPLE STATEMENTS In BASIC programs, you can write several statements on a single line by separating them with the {:} character. Since SB.EXE creates a BASIC program from the statements you give it, the {:} character will work just as it does in BASIC, but with an important exception: the special Structured BASIC statements mentioned here cannot be used in multiple lines. Instead, they ______ must have their own line whenever you use them. This restriction may change in another version of SB.EXE. Page 12 100784112 Preprocessor User's Manual ERROR MESSAGES ERROR MESSAGES When SB.EXE processes your program, it makes two sweeps or "passes" across it. The first pass checks for errors. There aren't very many that you can make, since most of your program will be passed through, untouched except for the addition of line numbers, to BASIC. There are, however, a few ways to produce an error message. The possible messages that you can get are listed below, along with an explanation of how to fix the statement that caused them. All of these messages will begin with the name of the file being processed (since the error might be in an INCLUDEd file) and the offending line number. label {name} defined previously at {file} line {n} If this error message is displayed it means you have defined the label {name} twice (or more...) in your program. A good candidate for the source of this problem is an INCLUDEd file with a duplicate of a label you are using in your program. label {name} referenced at {file} line {n} undefined This error message is saying that you have forgotten to define the label {name} in your program. Possible causes of this are forgetting an INCLUDE file (especially likely if you see a lot of these messages) or misspelling the label. label {name} type mismatch with {file} line {n} This error message is displayed when you try to GOTO a procedure name or DO a LABEL|. {type} block not active You used an ENDIF, ENDWHILE, or UNTIL statement in your program without first using IF, WHILE, or REPEAT. {type} block already begun at {file} line {n} You tried to put two ELSE statements in one IF block. You have probably forgotten an IF statement somewhere. procedure {name} already begun at {file} line {n} You cannot have two procedures started at the same time. You must end the first procedure, {name}, with an ENDPROC statement before you can begin your new procedure. Page 13 100784112 Preprocessor User's Manual procedure not begun first This error message means that an ENDPROC statement was found in your program when no PROCEDURE statement was active. no WHILE or REPEAT for BREAK This error message is displayed when you use a BREAK statement outside a WHILE or REPEAT blocks. Remember that a BREAK transfers control to the statement immediately after the nearest ENDWHILE or UNTIL. SB.EXE ABORTS SB.EXE ABORTS If you specify a source or object filename that can't be read or written to for some reason (such as the name being misspelled, the diskette having its write-protect notch covered, etc.) the preprocessor program will print the message: Can't open file: {filename.ext} If this happens, you should check to make sure that the source file can be read, that any INCLUDEd files it uses can be read, and that the object file can be written to. Page 14 100784112 Preprocessor User's Manual PREPROCESSOR SPEED PREPROCESSOR SPEED This version of SB.EXE can process your programs at the rate of 120-300 lines per minute. As you can see, this rate is highly variable and is based on a number of factors, such as the speed of your disk drives, the version of MS DOS you are using, even the location of the files on the diskette. If you have frequently-used INCLUDE files you might want to consider putting them on a RAM disk if you aren't going to change them often. This should improve processing time a lot. KNOWN BUGS KNOWN BUGS There are a two known bugs in this release of SB.EXE. The first involves writing the output BASIC program to a nearly-full diskette. When this happens, no warning error occurs, and only part of the program is written. Check to make sure this doesn't happen when your working diskettes are nearly full. The second bug concerns error recovery when many REPEAT, WHILE, and IF blocks are nested. When an error occurs, the error message might not tell you the block in error. Check all the logic blocks in the vicinty of the statements mentioned for an error. These bugs will be fixed in the next version of the Structured BASIC preprocessor. SB VS. BASIC SB VS. BASIC Once you've mastered the Structured BASIC statements, there aren't many reasons to continue entering and debugging BASIC programs the old way. You'll probably find that with a little practice Structured BASIC programs really are easier to write and maintain. The only reasons to modify the translated BASIC programs directly are: 1. Quick "patches" or minor changes to the BASIC program when the Structured BASIC source code isn't available or there isn't time to edit it again. (Such as when you're at the customer's office and the payroll program isn't working.) 2. "Fine tuning" for better performance, to straighten out Structured BASIC's "inside out" IF statements and extra GOTOs in programs where speed and memory size are crucial. Page 15 100784112 Preprocessor User's Manual STATEMENT REFERENCE STATEMENT REFERENCE Here's a list of all the special statements available to you in this version of SB.EXE. For a complete description of how to use them, see the individual sections in this manual. BREAK DO {procname} ELSE ELSIF ENDIF ENDPROC ENDWHILE IF {condition} IF {condition} BREAK IF {condition} DO {procname} IF {condition} GOSUB {procname} IF {condition} GOTO {procname} IF {condition} THEN {any BASIC statement} GOSUB {procname} GOTO {label} INCLUDE {d:filename.ext} ON n DO {procname1},{procname2},... ON COM(n) DO {procname} ON KEY(n) DO {procname} ON PEN DO {name} ON PLAY(n) DO {procname} ON STRIG(n) DO {procname} ON TIMER(n) DO {procname} ON n GOTO {label1},{label2},... ON ERROR GOTO {label} REPEAT RESTORE {label} RESUME {label} RETURN {label} UNTIL {condition} WHILE {condition} Page 16 100784112 Preprocessor User's Manual Page 17 100784112